home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / tlp4v11c / docu / vrclk.txt < prev   
Text File  |  1994-05-15  |  9KB  |  308 lines
  1. vrclk.obj function summary:
  2. ===========================
  3.  
  4. This list contains UNIX-like summaries for the routines that
  5. are currently contained in vrclkx.obj.
  6.  
  7. vrclkx.obj is intended for use with the tgdlp4xx.obj ModeX
  8. graphics driver. However this library could also act as a stand
  9. alone module. In order for vrclkx.obj to work the following
  10. hardware items are required:
  11.  
  12. - IBM compatible PC/XT/AT with 80188 CPU or above
  13. - a VGA card
  14.  
  15. vrclkc.obj is assembled for the COMPACT memory model. This means
  16. that all calls to procedures must be declared as NEAR while
  17. pointers to data are all FAR.
  18. vrclkl.obj is assembled for the LARGE memory model. In this
  19. model all calls to procedures as well as all pointers to data
  20. are to be declared as FAR.
  21.  
  22. vrclkx.obj expects all parameters to be passed using C calling
  23. conventions. The C calling mechanism is described in tgdlp4.txt.
  24.  
  25.  
  26. byte startvrclk(ubyte fcreset);
  27. initialize new timer interrupt and start frame counting
  28.  
  29. FUNCTION:
  30. Before using any of the vrclk library functions this routine
  31. must be called. It reprograms the system timer to generate
  32. interrupts synchronized to the vertical retrace of the VGA card
  33. and installs a new interrupt handler which will increment a
  34. frame counter every interrupt. This means you can concentrate
  35. fully on doing your graphics - wasting no unnecassary time on
  36. frame counting to keep a constant screen update rate for e.g.
  37. double-buffering.
  38. The initial value of the frame counter is passed in fcreset. In
  39. a double-buffered environment it is usefull to give the frame
  40. counter the graphics update frame rate when starting the vrclk
  41. system.
  42. Example for page double-buffering:
  43. Let's say your double buffer graphics update frame rate is 3
  44. (giving you 70/3 = 23,3 frames per second).
  45. Your program looks like this:
  46. ...
  47. #define UPDATE_RATE 3    /* graphics update frame rate */
  48. ...
  49. ubyte page=0;        /* initial graphics page to prepare */
  50. ...
  51.  
  52. /* prepare first graphics page */
  53. preparepage(page);
  54.  
  55. /* start frame counting */
  56. startvrclk(UPDATE_RATE);
  57. /* page double-buffering main loop */
  58. { /* immediately after startvrclk(UPDATE_RATE) was called
  59.    * vrclk() will return UPDATE_RATE...
  60.    */ 
  61.   while (vrclk()<UPDATE_RATE); resetvrclk();
  62.   /* ...which will consequently lead to the immediate display
  63.    * of the prepared first graphics page here */
  64.   displaypage(page);
  65.  
  66.   /* switch graphics page to prepare */
  67.   page=1-page;
  68.   /* wait for the prepared graphics page to appear on the
  69.    * screen
  70.    */
  71.   while (!vrclk());
  72.   /* ok, now it's time to prepare the hidden graphics page */
  73.   preparepage(page);
  74. };
  75.  
  76. Note:
  77. startvrclk() takes over the system timer (INT 08) and replaces
  78. the old timer interrupt handler by its own. The old timer handler
  79. is never being called by the startvrclk() interrupt service
  80. routine and hence all system functions related to INT 08h are
  81. suspended until stopvrclk() is called. Especially the system
  82. clock is stopped once the vrclk system is active. However you
  83. can reload the correct system time from your real time clock (if
  84. you own an AT type PC) by calling restoretime() once you have
  85. disabled the vrclk library services with stopvrclk().
  86.  
  87. INPUTS:
  88. fcreset: initial value of the interrupt frame counter.
  89.  
  90. RESULT:
  91. byte success: TRUE if the vrclk system was successfully
  92.           initialized,
  93.           FALSE if not (i.e. the vertical retrace clock is
  94.           already active).
  95.  
  96. BUGS:
  97. This procedure suspends system functions related to INT 08h until
  98. stopvrclk() is being called.
  99.  
  100. SEE ALSO:
  101. stopvrclk(), restoretime()
  102.  
  103.  
  104. void resetvrclk(void);
  105. zero the interrupt frame counter and the benchmark counter
  106.  
  107. FUNCTION:
  108. Once the frame counter has reached the desired update frame
  109. rate it is time to start a new display cycle. This means
  110. a) to set back the frame counter to zero - which is done by
  111.    this procedure and
  112. b) to display new/prepared graphics.
  113. It is most usefull to call resetvrclk() immediately after you
  114. have waited for the frame counter to get the value of the
  115. desired frame update rate - this will also assure that
  116. clkload()'s benchmark timer will be resetted correctly.
  117. See startvrclk(), clkload() for programming examples.
  118.  
  119. INPUTS:
  120. none
  121.  
  122. RESULT:
  123. none
  124.  
  125. BUGS:
  126. none known
  127.  
  128. SEE ALSO:
  129. startvrclk(), clkload()
  130.  
  131.  
  132. ubyte vrclk(void);
  133. get current value of the frame counter
  134.  
  135. FUNCTION:
  136. This procedure returns the current value of the interrupt frame
  137. counter. After calling startvrclk() the frame counter is
  138. increased automagically at the start of every frame without the
  139. user having to wait for the beginning of each frame and to
  140. increment the frame counter manually.
  141.  
  142. INPUTS:
  143. none
  144.  
  145. RESULT:
  146. ubyte framecnt: current value of the frame counter
  147.  
  148. BUGS:
  149. none known
  150.  
  151. SEE ALSO:
  152. startvrclk()
  153.  
  154.  
  155. byte stopvrclk(void);
  156. restore old system timer interrupt handler
  157.  
  158. FUNCTION:
  159. stopvrclk() is used to inactivate the vrclk system. It removes
  160. the system timer interrupt handler installed by startvrclk()
  161. and installs ye olde system timer interrupt service routine.
  162. After stopvrclk() you may want to call restoretime() to bring
  163. the system clock up to date.
  164.  
  165. INPUTS:
  166. none
  167.  
  168. RESULT:
  169. byte success: TRUE if the function was successfully executed,
  170.           FALSE if not (i.e. the vrclk system was not 
  171.           active).
  172.  
  173. SEE ALSO:
  174. startvrclk(), restoretime()
  175.  
  176.  
  177. byte restoretime(void);
  178. load the system clock with the values of the real time clock
  179.  
  180. FUNCTION:
  181. Once the vertical retrace clock was enabled by calling
  182. startvrclk() the system clock will stop working. The clock will
  183. begin to work again after the vrclk system was disabled by
  184. stopvrclk(). But the system clock will contain an incorrect time.
  185. This procedure brings the system clock up to date by loading the
  186. values of the AT real time clock into it. restoretime() should
  187. be called immediately after stopvrclk(). Of couse, it only works
  188. on an AT type PC which has a real time clock.
  189.  
  190. INPUTS:
  191. none
  192.  
  193. RESULT:
  194. byte success: TRUE, if the system clock was succesfully reloaded
  195.           with the values of the real time clock;
  196.           FALSE if not (battery of real time clock empty).
  197.  
  198. BUGS:
  199. none known
  200.  
  201. SEE ALSO:
  202. startvrclk(), stopvrclk()
  203.  
  204.  
  205. uword clkload(void);
  206. get value of the benchmark timer
  207.  
  208. FUNCTION:
  209. The vrclk library has an integrated benchmark timer which will
  210. be activated by startvrclk(). This benchmark timer can be used
  211. to find out how much CPU time a certain routine requires. The
  212. benchmark counter subdivides a frame into 64 cycles - this means
  213. if clkload() returns 64 exactly one frame has passed. There
  214. may be more precise ways to benchmark a procedure. But
  215. clkload() provides a benchmark in a real world environment -
  216. without adding any CPU overhead. In fact you can run clkload()
  217. on the fly as demonstrated here:
  218. ...
  219. #define UPDATE_RATE 2    /* graphics update frame rate */
  220. ...
  221. ubyte page=0;        /* initial graphics page to prepare */
  222. uword sysload;        /* variable to store benchmark timer */
  223. ...
  224.  
  225. /* prepare first graphics page */
  226. preparepage(page);
  227.  
  228. /* start frame counting */
  229. startvrclk(UPDATE_RATE);
  230. /* page double-buffering main loop */
  231. { /* when resetvrclk() is used immediately after the desired
  232.    * update frame rate was reached, the benchmark timer will
  233.    * be resetted properly.
  234.    */
  235.   while (vrclk()<UPDATE_RATE); resetvrclk();
  236.   /* benchmarking begins HERE */
  237.   displaypage(page);
  238.  
  239.   /* switch graphics page to prepare */
  240.   page=1-page;
  241.   /* wait for the prepared graphics page to appear on the
  242.    * screen
  243.    */
  244.   while (!vrclk());
  245.   /* ok, now it's time to prepare the hidden graphics page */
  246.   preparepage(page);
  247.  
  248.   /* how long took this? How many % of CPU time are left?
  249.    * let's find out...
  250.    */
  251.   sysload=clkload(); /* benchmarking stops HERE */
  252.   /* since our frame update rate is 2 sysload will contain
  253.    * anything from 0-128 (actually from 64-128 since we wait
  254.    * the first frame for the prepared page to appear on the
  255.    * screen)
  256.    *
  257.    * let's calc the %-tual CPU load
  258.    */
  259.   sysload=(sysload*100)/(UPDATE_RATE<<6);
  260.   /* that's all! Wasn't that easy? And you get the CPU load
  261.    * of each double-buffer cycle in a real world environment
  262.    * without wasting valuable CPU bandwidth on benchmarking!
  263.    */
  264. };
  265.  
  266. INPUTS:
  267. none
  268.  
  269. RESULT:
  270. uword sysload: value of the internal benchmark timer. The
  271.            benchmark timer slices a frame into 64 subcycles.
  272.            Hence clkload() will return 64 when exactly one
  273.            frame has passed.
  274.  
  275. BUGS:
  276. none known
  277.  
  278. SEE ALSO:
  279. startvrclk(), vrclk(), resetvrclk()
  280.  
  281.  
  282.  
  283. APPENDIX:
  284. =========
  285.  
  286. A) Simulating tgdlp4xx.obj's waittof() with functions of the
  287.    vrclk library:
  288.  
  289. (It is assumed that you have started the vrclk system with
  290. startvrclk().)
  291.  
  292. resetvrclk(); while (!vrclk());
  293.  
  294.  
  295. B) Simulating tgdsuppx.obj's framewait(frames) with functions of
  296.    the vrclk library:
  297.  
  298. (It is assumed that you have started the vrclk system with
  299. startvrclk().)
  300.  
  301. resetvrclk(); while (vrclk()<frames);
  302.  
  303. Note that tgdsuppx.obj's framewait() expects a UWORD value, while
  304. vrclkx.obj's vrclk() returns a UBYTE value. In other words:
  305. with framewait() you can wait max. 65535 frames while with
  306. vrclk() only 255!
  307.  
  308.